puriFlash® API 1.0.0

Notice

This document is currently being drafted and is not complete. (Draft: 4)

Overview

Designed with flexibility and ease of use in mind, this API enables remote control of a puriFlash® system and all its peripherals. It makes it easy to manage the entire purification processes in a laboratory environment.

Features

  • System Control: seamless management of connections to puriFlash® systems and their various peripherals.

  • Advanced Queue Management: Organize and monitor sequential and parallel processes with efficient queuing.

  • Real-time Monitoring: Stay informed with system status updates and other collection, elution and detection measures.

  • Anomaly Detection: Quickly identify and report errors and issues.

Hardware support

Compatible with all puriFlash® series.

Communication protocol

  • MQTT (Message Queuing Telemetry Transport): lightweight publish/subscribe messaging protocol.

Getting started

Phoenix Server Application

A cross-platform console application that can be run as a service on any computer connected to the puriFlash® system.

Activation: Upon the initial launch of the Phoenix Server, you'll need to obtain a license key for activation. Contact the support team with the unique key generated by the application to activate your server.
  • Windows

    • Run as Administrator: Start 'phoenix-server.exe' with administrator privileges.

    • Disable Quick Edit Mode: Turn off the terminal's 'Quick Edit' mode to prevent unintentional pauses in the server operation.

    • Windows Defender Exclusion: Add the Phoenix Server application folder to the exclusion list in Windows Defender to avoid any interference from the operating system's security features.

  • MacOS / Linux

    • No further steps are required beyond the usual activation process. Simply launch the Phoenix Server application and activate it using the license key supplied.

Configuration

The Phoenix Server uses a configuration file named phoenix-server-config.json to manage its connection and operations with the puriFlash® system. Similarly, the puriflash-config.json file sets up the puriFlash® system itself

It's crucial that these configurations accurately match the actual system setup to avoid errors. If not, the server will halt with an error message.

For setup details, check the SystemConfiguration and ServerConfiguration schemas in the components/schemas section of our documentation. Make sure your configuration files, found in the config folder of the application's root.

Tools

  • API Exploration: Use tools like Postman or MQTTX to explore and interact with the API.

  • Performance Monitoring: Connect using JConsole tool to the application's JMX server at {host}:9010.

Examples

(TODO: Additional project examples and usage scenarios will be provided on GitHub.)

  • #api
  • #remote
  • #chromatography

Servers

  • tcp://{host}:{port}/tcpMQTT 5.0
    object
    host
    required
    string
    Default value:"127.0.0.1"
    port
    required
    string

    Default MQTT port.

    Default value:"1883"
    Security:
    • User/Password

      This API is meant to be used within a secure local network environment. Therefore, no authentication credentials are required for connecting to the MQTT broker.

  • ws://{host}:{port}/mqttwsMQTT 5.0 / WEBSOCKET
    object
    host
    required
    string
    Default value:"127.0.0.1"
    port
    required
    string
    Default value:"8083"
    Security:
    • User/Password

      This API is meant to be used within a secure local network environment. Therefore, no authentication credentials are required for connecting to the MQTT broker.

Operations

  • SEND puriflash/request/{clientId}

    Channel used for sending requests to the system.

    Operation IDRequestMessage

    Available only on servers:

    object
    clientId
    required
    string

    MQTT Client unique identifier.

    object

    Accepts the following message:

    Request

    This message contains the information needed to send a request to the system. Depending on the command used, a specific parameter may be required.

    object

    Defines the structure for sending commands to the system. Each request must specify a command. Some commands may require additional parameters to execute properly.

    Examples

  • RECEIVE puriflash/response/{clientId}

    Channel for receiving responses from the system.

    Operation IDResponseMessage

    Available only on servers:

    object
    clientId
    required
    string

    MQTT Client unique identifier.

    object

    Accepts the following message:

    Response

    Response message from the system. Contains information about the execution status of commands and any results or data.

    object

    Response message to a specific request.

    Examples

  • RECEIVE puriflash/status

    Channel for receiving status updates from the system.

    Operation IDStatusMessage

    Available only on servers:

    object

    Accepts the following message:

    Status

    Status updates from the system.

    object

    Current system status.

    Examples

  • RECEIVE puriflash/error

    Channel for receiving error messages from the system.

    Operation IDErrorMessage

    Available only on servers:

    object

    Accepts the following message:

    Error

    Error message indicating issues or failures. Includes error codes and a description for troubleshooting.

    object

    System detailed error.

    Examples

  • RECEIVE puriflash/configuration

    Channel for receiving system configuration on reload or first connection.

    Operation IDConfigurationMessage

    Available only on servers:

    object

    Accepts the following message:

    System configuration

    Configuration message showing all system and peripheral parameters.

    object

    Comprehensive configuration object for the system, encapsulating all settings for system operation, including model, connection, module configurations, and more.

    Examples

  • RECEIVE puriflash/collector/status

    Channel for receiving collector status.

    Operation IDCollectorStatusMessage

    Available only on servers:

    object

    Accepts the following message:

    Collector status

    Collector status updates from the system.

    object

    Collector status

    Examples

  • RECEIVE puriflash/collector/tube

    Channel for receiving collector current tube.

    Operation IDCollectorCurrentTubeMessage

    Available only on servers:

    object

    Accepts the following message:

    Collector current tube

    Current tube updates indicating number, index and volume.

    object

    Tube

    Examples

  • RECEIVE puriflash/collection/tubes/data

    Channel for receiving collection tubes data messages from the system.

    Operation IDCollectionTubesDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Collection tubes data

    Collection data message indicating tube, rack and peak number, collected volume and detectors data.

    array<object>

    Collection tubes data

    Examples

  • RECEIVE puriflash/elution/global/data

    Channel for receiving elution data.

    Operation IDElutionDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Elution data

    Elution data message indicating time, percentages, flow rate and pressure.

    object

    Elution data

    Examples

  • RECEIVE puriflash/detection/global/data

    Channel for receiving synchronized detection data during a purification process.

    Operation IDDetectionDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Detection data

    Detection data message indicating time, flow rate, detection channels, value and threshold.

    object

    Detection data

    Examples

  • RECEIVE puriflash/detection/unsync/uv/data

    Channel for receiving unsynchronized UV detection data during an elution purge process.

    Operation IDDetectionUnsyncUVDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Detection unsynchronized UV data

    Detection data message indicating time, flow rate, uv channels, value and threshold.

    object

    Detection data

    Examples

  • RECEIVE puriflash/detection/unsync/elsd/data

    Channel for receiving unsynchronized ELSD detection data during an ELSD purge process.

    Operation IDDetectionUnsyncElsdDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Detection unsynchronized ELSD data

    Detection data message indicating time, flow rate, ELSD channel, value and threshold.

    object

    Detection data

    Examples

  • RECEIVE puriflash/detection/unsync/uv/data

    Channel for receiving unsynchronized Mass detection data during a Mass purge process.

    Operation IDDetectionUnsyncMassDataMessage

    Available only on servers:

    object

    Accepts the following message:

    Detection unsynchronized Mass data

    Detection data message indicating time, flow rate, Mass channels, value and threshold.

    object

    Detection data

    Examples

  • RECEIVE puriflash/servicequeue/status

    Channel for receiving service queue status.

    Operation IDServiceQueueStatusMessage

    Available only on servers:

    object

    Accepts the following message:

    Service queue status

    Service queue status indicating global state and detailed current process status

    object

    Global service queue status and current block status.

    Examples

  • RECEIVE puriflash/split/mass/status

    Channel for receiving Mass split status.

    Operation IDMassSplitStatusMessage

    Available only on servers:

    object

    Accepts the following message:

    Mass split status

    Mass split status message indicating valve and pumps states, volumes, pressures, flow rates and alarms.

    object

    Examples

  • RECEIVE puriflash/autosampler/status

    Channel for receiving Auto sampler status.

    Operation IDAutoSamplerStatusMessage

    Available only on servers:

    object

    Accepts the following message:

    Auto sampler status

    Auto sampler status indicating state, total steps, step, total time, time and description

    object

    Auto sampler detailed status

    Examples

Messages

  • #1RequestRequestMessage

    This message contains the information needed to send a request to the system. Depending on the command used, a specific parameter may be required.

    Message IDRequestMessage
    object

    Defines the structure for sending commands to the system. Each request must specify a command. Some commands may require additional parameters to execute properly.

  • #2ResponseResponseMessage

    Response message from the system. Contains information about the execution status of commands and any results or data.

    Message IDResponseMessage
    object

    Response message to a specific request.

  • #3StatusStatusMessage

    Status updates from the system.

    Message IDStatusMessage
    object

    Current system status.

  • #4ErrorErrorMessage

    Error message indicating issues or failures. Includes error codes and a description for troubleshooting.

    Message IDErrorMessage
    object

    System detailed error.

  • #5System configurationConfigurationMessage

    Configuration message showing all system and peripheral parameters.

    Message IDConfigurationMessage
    object

    Comprehensive configuration object for the system, encapsulating all settings for system operation, including model, connection, module configurations, and more.

  • #6Collector statusCollectorStatusMessage

    Collector status updates from the system.

    Message IDCollectorStatusMessage
    object

    Collector status

  • #7Collector current tubeCollectorCurrentTubeMessage

    Current tube updates indicating number, index and volume.

    Message IDCollectorCurrentTubeMessage
    object

    Tube

  • #8Collection tubes dataCollectionTubesDataMessage

    Collection data message indicating tube, rack and peak number, collected volume and detectors data.

    Message IDCollectionTubesDataMessage
    array<object>

    Collection tubes data

  • #9Elution dataElutionDataMessage

    Elution data message indicating time, percentages, flow rate and pressure.

    Message IDElutionDataMessage
    object

    Elution data

  • #10Detection dataDetectionDataMessage

    Detection data message indicating time, flow rate, detection channels, value and threshold.

    Message IDDetectionDataMessage
    object

    Detection data

  • #11Detection unsynchronized UV dataDetectionUnsyncUVDataMessage

    Detection data message indicating time, flow rate, uv channels, value and threshold.

    Message IDDetectionUnsyncUVDataMessage
    object

    Detection data

  • #12Detection unsynchronized ELSD dataDetectionUnsyncElsdDataMessage

    Detection data message indicating time, flow rate, ELSD channel, value and threshold.

    Message IDDetectionUnsyncElsdDataMessage
    object

    Detection data

  • #13Detection unsynchronized Mass dataDetectionUnsyncMassDataMessage

    Detection data message indicating time, flow rate, Mass channels, value and threshold.

    Message IDDetectionUnsyncMassDataMessage
    object

    Detection data

  • #14Service queue statusServiceQueueStatusMessage

    Service queue status indicating global state and detailed current process status

    Message IDServiceQueueStatusMessage
    object

    Global service queue status and current block status.

  • #15Mass split statusMassSplitStatusMessage

    Mass split status message indicating valve and pumps states, volumes, pressures, flow rates and alarms.

    Message IDMassSplitStatusMessage
    object
  • #16Auto sampler statusAutoSamplerStatusMessage

    Auto sampler status indicating state, total steps, step, total time, time and description

    Message IDAutoSamplerStatusMessage
    object

    Auto sampler detailed status

Schemas

  • object

    Comprehensive configuration object for the system, encapsulating all settings for system operation, including model, connection, module configurations, and more.

  • object

    Configuration settings for establishing a connection to the system. Includes options for port detection and connection automation.

  • object

    Configuration settings for the pump module of the system. Includes details about the pump model, maximum flow rate, maximum pressure, and valve configurations.

  • object

    Configuration settings for the collector module of the system. This includes parameters for capacity, sensor options, physical offsets for precise positioning, and other specific settings relevant to collector operation.

  • object

    Configuration settings for the UV detector module of the system. It outlines the specifications for the type of UV detector used.

  • object

    Configuration parameters for the ELSD module. It includes settings for the ELSD detector and split.

  • object

    Specific configuration settings for the ELSD detector. This includes parameters like nebulization duration and whether the detector is internal or external to the system.

  • object

    Configuration for the ELSD split, including settings for the makeup pump flow rate and the valve rotation period.

  • object

    Configuration parameters for the Mass module. It includes settings for the Mass detector and split.

  • object

    Specific configuration settings for the Mass detector. This includes parameters like model, nebulization duration, and adjustments for capillary temperature and voltage used during the detector's stabilization.

  • object

    Configuration for the Mass split, including settings for the makeup and dilution pumps, and the valve rotation period.

  • object

    Configuration parameters for the auto-sampler module. It includes settings for the rack configuration, sample handling parameters, and physical positioning for precise sample injection.

  • object

    This schema defines the configuration for the Phoenix Server application, specifying how it connects to and interacts with the puriFlash® system. It includes network settings, MQTT broker options, and system initialization preferences.

  • object

    Defines the structure for sending commands to the system. Each request must specify a command. Some commands may require additional parameters to execute properly.

  • array<object>

    An array consisting of configurations for each detector channel used in the method. Each element in the array contains the parameters for simulating a detector response.

  • object

    Defines the simulation parameters for a specific type of detector channel, including the channel type and the steps for simulation.

  • object

    Represents a segment of the simulation

  • object

    List of sequential service queue blocks

  • array<object>

    Parallel processes parameters.

  • object

    Process parameters

  • object

    Pre purification parameters

  • object

    Post purification parameters

  • object

    Purification parameters

  • object

    Stop mode parameters

  • object

    Injection parameters

  • object

    Auto sampler injection parameters

  • object

    Injection pump parameters

  • object

    Column parameters

  • object

    Solvents parameters

  • object

    Solvent parameters

  • object

    Elution purge parameters

  • object

    Detection parameters

  • object

    Elution parameters

  • object
  • object

    Mass parameters

  • object

    Represents a step in the elution process with specific conditions for solvent percentages, flow rate, and whether the step is part of a gradient or an isocratic elution. Note: The sum of the percentages of solvents A, B, C, and D must equal 100% to ensure a valid solvent composition for each step.

  • restricted any

    Collection step

  • object

    Detection channel

  • object

    Collection parameters

  • object

    Needle rinsing parameters

  • object

    ELSD purge parameters

  • object

    ELSD prime purge parameters

  • object

    Mass purge parameters

  • object

    Response message to a specific request.

  • object

    Current system status.

  • object

    System detailed error.

  • object

    Error type object composed of a code and a description

  • object

    Collector status

  • array<object>

    Collection tubes data

  • object

    Tube data

  • object

    Tube

  • object

    Tube index

  • object

    Tube number

  • object

    A map where each key is a string representing a range (e.g., "[200..400]") and each value conforms to the DetectionDataMap schema. The range format in the key is "[min..max]".

  • object

    Elution data

  • object

    Elution channel value

  • object

    Elution channel

  • object

    Detection data

  • object

    Detection channel value

  • ServiceState
    string

    Represents the service execution state.

      Allowed values:
    • "IDLE"
    • "RUNNING"
    • "PAUSED"
    • "CANCELLED"
    • "FAILED"
    • "DONE"
  • ProcessType
    string

    Specifies the process type.

      Allowed values:
    • "PURIFICATION"
    • "ELUTION_PURGE"
    • "ELSD_PURGE"
    • "ELSD_PRIME_PURGE"
    • "PRE_PURIFICATION"
    • "POST_PURIFICATION"
  • object

    Defines the process execution state, time spent (ms), progress, and a descriptive note if any.

  • object

    Progress status of all parallel processes.

  • object

    Service queue entry 'block' status.

  • object

    Global service queue status and current block status.

  • object
  • object

    Auto sampler detailed status

  • ClientId
    string

    MQTT client unique identifier used during connection

  • object
  • object